import { Attachment } from '../types/types';

/**
 * 通用的工具调用请求结构
 * 任何具体的服务（OpenAI, Mock, WebAPI）都需要将自己的私有格式转换为此标准格式
 */
export interface AgentToolRequest {
    id: string;           // 唯一调用ID
    toolName: string;     // 工具名称
    toolArgs: Record<string, any>; // 解析后的参数对象
}

/**
 * 通用的 Agent 回调接口
 * Controller 通过此回调接收来自 Service 的反馈
 */
export interface IAgentCallbacks {
    /**
     * 收到流式文本块
     * @param chunk 增量文本
     */
    onChunk: (chunk: string) => void;

    /**
     * Agent 请求调用工具
     * 关键点：这里使用通用的 AgentToolRequest，解耦了具体的 AI SDK
     */
    onToolRequest: (toolCalls: AgentToolRequest[]) => void;

    /**
     * 发生错误
     */
    onError: (error: Error) => void;
}

/**
 * 核心服务接口
 * 所有的具体服务（OpenAI, Mock, WebAPI 等）都要实现此接口
 */
export interface IAgentService {
    /**
     * 初始化服务 (加载配置、建立连接等)
     */
    initialize(): Promise<void>;

    /**
     * 发送用户消息
     * @param text 用户文本
     * @param attachments 附件
     * @param callbacks 回调处理
     */
    sendMessage(
        text: string,
        attachments: Attachment[] | undefined,
        callbacks: IAgentCallbacks
    ): Promise<void>;

    /**
     * 处理工具执行结果并回传给 Agent
     * 这是 Agent "思考-执行-再思考" 循环的关键
     */
    processToolResults(
        toolResults: { toolCallId: string; output: string }[],
        callbacks: IAgentCallbacks
    ): Promise<void>;
    
}